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1.0 Introduction 


This document contains a Reference Guide to the USPS Tracking/Delivery Confirmation Label APIs. See 
the Developers Guide to learn the administrative process for gaining access to the Web Tools APIs as 
well as the basic mechanism for calling the APIs and processing the results. The Developer’s Guide also 
contains information on testing and troubleshooting. 


Note: The Request Parameter sections present the XML input tags for generating live requests along with 
the restrictions on the values allowed. An error message will be returned if an incorrect value is entered. 
Also, be aware of the maximum character amounts allowed for some tags. If the user enters more than 
those amounts, an error will not be generated. Web Tools will simply pass in the characters up to the 
maximum amount allowed and disregard the rest. This is important since the resulting value could 
prevent a correct response. 


When building the XML request, pay particular attention to the order and case for tags. An error message 
will be returned if an incorrect value is entered. Remember that all data and attribute values in this 
document are for illustration purposes and are to be replaced by your actual values. For instance, a line 
of sample code may be: 


<TrackID> EJ123456780US </TrackID> 
In this instance, you will replace “EJ123456780US’ with the tracking ID for the package. 


1.1. Before you get started: 


For information on registering and getting started with Web Tools, please refer to the Step-By-Step guide 
found on the Web Tools Technical Documentation Page. 


1.2 Tracking Service APlis 


To obtain Package Tracking API (API=TrackV2) access, users will need to contact the USPS Web Tools 
Program Office to request access and supply additional information for customer verification. Note: This 
applies to both TrackV2 API simplified track requests (i.e., “TrackRequest’) and TrackV2 API detailed 
track requests (i.e., “TrackFieldRequest”). Users should follow these steps to submit a request for 


Tracking APIs access: Navigate to: https://usps.force.com/emailus/s/web-tools-inquiry and provide user 
name (Web Tools User ID), select “Tracking APIs”, select “Track API” and submit the request with the 


following information below in the “Additional Information” text box: 
Web Tools UserID: 

Mailer ID (MID): 

Company Name: 

Requester First and Last Name: 

Requester Email: 

Requester Phone number: 

Mailing Address: 

Mailing City: 

Mailing State: 

Mailing Zip Code: 

PROD Registration Date: 

API access requested: Package Tracking (APl=TrackV2) 
Anticipated volume: 

Any additional information from the customer: 


Four service APIs are offered in conjunction with “Revision=1” of the Package Tracking “Fields” API: 
Track and Confirm by Email, Proof of Delivery, Tracking Proof of Delivery, and Return Receipt Electronic. 
The response data from Track/Confirm Fields request determines which services are available for a 
tracking ID. Each request input to the Web Tools server for the tracking service APIs is limited to one 
tracking ID. These APIs require additional permissions from the WebTools Program Office in order to gain 
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access. When you request access for these APIs, please identify your anticipated API volume, mailer ID, 
and how you will be utilizing this API. A mailer identification number (MID) is a 6 or 9-digit number 
assigned to a customer through the USPS Business Customer Gateway (BCG). Please refer to the 
following links for help: 


e = https://gateway.usps.com/eAdmin/view/knowledge?securityld=MID 
e =https://postalpro.usps.com/mailing/mailer-id 


2.0 Package Track API 


2.1 Overview 


The Track/Confirm Web Tools API provides tracking status and delivery information for USPS packages. 
The Track/Confirm API limits the data requested to thirty-five (35) packages per transaction. 


Note: The data returned by the Package Track Web Tools API is intended for display only. The content or 


sequence of the String data returned by the API may change. Consequently, if you desire to apply any 
kind of logic against the tracking data, then you will need to use the Track/Confirm fields. 


2.1.1 API Signature Table 
| Scheme Host Path API XML 


https:// secure.shippingapis.com | /ShippingAPl.dll?_ | APl=TrackV2 | &XML=(see below) 


2.2 Request Descriptions 


=e r | T 7 
Tag Name Occurs Descriptions Type Validation 


TrackRequest Required | APl=TrackV2 (Alias) 


TrackRequest / Required | This attribute specifies your WebTools | String 
USERID ID. See the Developers Guide for 

information on obtaining your USERID 

For example: 

<USERID="XXXXXXXXXX”> 


TrackRequest / Required | Must be alphanumeric characters. String | minOccurs="1" 
TrackID For example: <TrackID 
ID="EJ123456780US"> 
</TrackID> 


TrackRequest Required (Alias) 


2.2.1 Sample Request 


Request: Package Track 
<TrackRequest USERID="XXXXXXXXXXXX"> 


<TrackID ID="XXXXXXXXXXX1"></TrackID> 
<TrackID ID="XXXXXXXXXXX2"></TrackID> 
</TrackRequest> 


2.3. Response Descriptions 


TrackResponse Required (Alias) 
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TrackResponse / Required | A unique identification String minOccurs="1" 

RequestSeqNumber number for a request. The 
same number will show in 
the response for this 
request. 


TrackResults / ID Required | Tracking ID String 

TrackResponse / (Group) 

Trackinfo 

TrackResponse / Required String minOccurs="0" 
TracklInfo / 

DeliveryNotificationDate 

TrackResponse / Optional Expected delivery date String minOccurs="0" 
TrackInfo / 

ExpectedDeliveryDate 

TrackResponse / Optional Expected Delivery Time String minOccurs="0" 
TracklInfo / 

ExpectedDeliveryTime 


TrackResponse / Optional Guaranteed Delivery Date String minOccurs="0" 
TrackInfo / — Global Express Mail 
GuaranteedDeliveryDate only: certain countries 
provide a guarantee 
delivery 

For Example: April 15, 
2020 

Or 

3 Business Days 


TrackResponse / Optional Summary of the status of String 
TrackInfo / the shipment, ie In-Transit, 
TrackSummary Delivered, etc. 

For example: February 5 

7:28 pm ENROUTE 33699 


TrackResponse / Optional Scan statuses from points String minOccurs="0" 
Trackinfo / TrackDetail in transit. 
TrackResponse Required (Alias) 

2.3.1 Sample Response 


Response: Package Track 
<TrackResponse> 


<TrackInfo ID="XXXXXXXXXXX1"> 

<TrackSummary> Your item was delivered at 6:50 am on February 6 in BARTOW FL 
33830.</TrackSummary> 

<TrackDetail>February 6 6:49 am NOTICE LEFT BARTOW FL 33830</TrackDetail> 
<TrackDetail>February 6 6:48 am ARRIVAL AT UNIT BARTOW FL 33830</TrackDetail> 
<TrackDetail>February 6 3:49 am ARRIVAL AT UNIT LAKELAND FL 33805</TrackDetail> 
<TrackDetail>February 5 7:28 pm ENROUTE 33699</TrackDetail> 

<TrackDetail>February 5 7:18 pm ACCEPT OR PICKUP 33699</TrackDetail> 
</Tracklnfo> 

<TrackInfo ID="XXXXXXXXXXX2"> 
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<TrackSummary There is no record of that mail item. If it was mailed recently, It may not yet be tracked. 
Please try again later. </TrackSummary> 
</TrackResponse> 


3.0 Package Tracking “Fields” API 


3.1 Overview 


The Package Tracking “Fields” API is similar to the Package Track API except for the request fields, API 
name, and the return information. Data returned still contains the detail and summary information, but this 
information is broken down into fields instead of having only one line of text. Up to 10 tracking IDs may be 
contained in each API request to the Web Tools server. 


3.1.1. API Signature 
|Scheme_ Host Path API XML 


https:// | secure.shippingapis.com | /ShippingAPI.dll? APl=TrackV2 &XML=(see below) 


3.2 Request Descriptions 


TrackFieldRequest Required |APl=TrackV2 (Alias) 


TrackFieldRequest/ (Required |This attribute specifies your Web Tools ID. |String 
USERID See the Developers Guide for information 

on obtaining your USERID. 

For Example: 

<USERID="XXXXXXXXXXXX’> 
TrackFieldRequest/ (Required |This is for versioning of the API's andfor (Integer (minOccurs="0" 
Revision triggering response tags for future 

versions. In this API use a value of 1 to 

return all available response tags and 

trigger new functionality. 

For example: <Revision>1</Revision> 


Optional /User IP address. Required when String minOccurs="0" 
Clientlp TrackFieldRequest[Revision='1']. 
For example: 


<Clientlp>137.0.0.1</Clientlp> 


TrackFieldRequest/ /|Required |External integrators should pass company /|String minOccurs="0" 
Sourceld name. Pattern="[0- 


For example: <Sourceld>XYZ 9]{5}" 
Corp</Sourceld> 


Required |Package Tracking ID. Must be String minOccurs="1" 
alphanumeric characters. 
For example: <TrackID 
ID="EJ123456780US"></TrackID> 


TrackFieldRequest/ (Optional 5 digit destination zip code. String minOccurs="0" 
TrackID / For example: 
DestinationZipCode <DestinationZipCode>12345</Destination 

ZipCode> 


TrackFieldRequest/ (Optional (Mailing date of package. Format: YYYY-  |String minOccurs="0" 
TrackID / MailingDate MM-DD 
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For example: <MailingDate>2010-01- 
01</MailingDate> 


TrackFieldRequest Required (Alias) 


3.2.1 Sample Request 


Request: Track and Confirm 
<TrackFieldRequest USERID="XXXXXXXXXXXX"> 


<Revision>1</Revision> 
<Clientlp>122.3.3</Clientlp> 
<Sourceld>XYZ Corp</Sourceld> 
<TrackID ID="XXXXXXXXXXXXXXXX"/> 
</TrackFieldRequest> 


3.3 Response Descriptions 


TrackResponse Required (Alias) 
TrackResponse Required (Group) 
/ Trackinfo 

TrackResponse Required | Package Tracking ID number. String 

/ Trackinfo / ID 


TrackResponse | Optional | Guaranteed Delivery Date — Global String 
/ TrackInfo / Express Mail only: certain countries 

Guaranteed provide a guarantee delivery. 

Delivery Date 

TrackResponse | Optional | Signifies if the mail piece is eSOF eligible. Boolean 
/ TrackInfo / 

eSOFEligible 

TrackResponse Required | Tracking Summary Information. (Group) 
/ TrackInfo / once 

TrackSummary 

TrackResponse Required | The time of the event. String 
/ TrackInfo / 

TrackSummary / 

EventTime 

TrackResponse Required | The date of the event. String 
/ TrackInfo / 

TrackSummary / 

EventDate 

TrackResponse Required | The event type (e.g., Enroute). String 
/ TrackInfo / 

TrackSummary / 

Event 


TrackResponse Required | City where the event occurred. String 
/ TrackInfo / 
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| Descriptions Validation 
TrackSummary / 
EventCity 


TrackResponse Required | State where the event occurred. String 
/ TrackInfo / 

TrackSummary / 

EventState 

TrackResponse Required | ZIP Code of the event. String 
/ TrackInfo / 

TrackSummary / 

EventZIPCode 

TrackResponse | Optional | Country where the event occurred. String 
/ TrackInfo / 

TrackSummary / 

EventCountry 

TrackResponse | Optional | Company name if delivered toa company. | String 
/ TrackInfo / 

TrackSummary / 

FirmName 

TrackResponse | Optional String 
/ TrackInfo / 

TrackSummary / 

Name 


Name of the persons signing for delivery 
(if available). 


TrackResponse | Optional | The event code. String 
/ TrackInfo / 

TrackSummary / 

EventCode 


TrackResponse 
/ TrackInfo / 


Optional | The action code. String 
TrackSummary / 
ActionCode 


TrackResponse | Optional | The reason code String 
/ TrackInfo / 
TrackSummary / 
ReasonCode 


TrackResponse Required | Tracking Detail Information. This group is (Group) 
/ TrackInfo / once repeatable. 

TrackDetail 

TrackResponse Required | The time of the event. String 
/ TrackInfo / 

TrackDetail / 

EventTime 

TrackResponse Required | The date of the event. String 
/ TrackInfo / 

TrackDetail / 

EventDate 


TrackResponse Required | The event type (e.g., Enroute). String 
/ TrackInfo / 


USPS Web Tools User Guide 


TrackDetail / 
Event 


TrackResponse Required | The city where the event occurred. String 
/ TrackInfo / 

TrackDetail / 

EventCity 

TrackResponse Required | The state where the event occurred. String 
/ TrackInfo / 

TrackDetail / 

EventState 

TrackResponse Required | The ZIP Code of the event String 
/ TrackInfo / 

TrackDetail / 

EventZIPCode 

TrackResponse | Optional | The country where the event occurred. String 
/ TrackInfo / 

TrackDetail / 

EventCountry 

TrackResponse | Optional | The company name if delivered to a String 
/ TrackInfo / company. 

TrackDetail / 

FirmName 

TrackResponse | Optional | The name ofthe persons signing for String 
/ TrackInfo / delivery (if available). 

TrackDetail / 

Name 


TrackResponse True/False field indicating the person String Enumeration= 
/ TrackInfo / signing as an Authorized Agent. e True 


Optional 
TrackDetail / e False 
AuthorizedAgent 
TrackResponse | Optional | The event code String 
/ TrackInfo / 
TrackDetail / 
EventCode 
TrackResponse | Optional | The action code String 
/ TrackInfo / 
TrackDetail / 
ActionCode 
TrackResponse | Optional | The reason code String 
/ Trackinfo / 
TrackDetail / 
ReasonCode 


TrackResponse Required (Alias) 
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3.3.1 Response Descriptions Continued (Revision = 1) 


TrackResults/ Required A unique identification number fora _ | Integer 
RequestSeqNum | max 1 request. The same number that 
ber was provided in the request. 

For example: 122 

Required The tracking number ID submitted String 
max 10 through the request 

For example: EA123456795US 

12887393000019 
TrackResults / Optional Additional package information String 
TrackInfo / 
Additionallnfo 
TrackResults / Optional Additional ADP scripting specific to | String 
TrackInfo / the ADP Type code 
ADPScripting 
TrackResults / Optional Information regarding availability of | String 
TrackInfo / Restore service function 
ArchiveRestoreln For example Yes 
fo 
TrackResults / Optional Additional Label on the mail piece String 
TracklInfo / For example: EA123456785US 
AssociatedLabel This is not currently populated. 
TrackResults / Optional True/False field indicating the item String 
TrackInfo / qualifies for the customer to 
CarrierRelease electronically authorize shipment 

release. 


TrackResults / 
TracklInfo ID 


TrackResults / Optional Mail Class of the mail piece (human _ | String Enumerations= 

Trackinfo / Class readable). This will also include the e True 
service standard message if it e False 
exists. 


No Default of False. 


TrackResults / Optional Mail Class of the mail piece (code). | String 
TrackInfo / For example:EX, PM, CP, IP 
ClassofMailCode 

TrackResults / Optional The destination city. For example: String 
TrackInfo / Rochester 

DestinationCity 

TrackResults / Optional The destination country code. For String 
TrackInfo / example:MX, CA 

DestinationCount 

ryCode 

TrackResults / Optional The destination State. For example: | String 
TrackInfo / NY 

DestinationState 

TrackResults / Optional The destination ZIP code. For String 
TrackInfo / example:20024 

DestinationZip 
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TrackResults / Optional Edited Label ID or Full Label ID. String Enumerations= 
TrackInfo / Used only when Source ID is IVR e True 
EditedLabellD For example:EA123456795US e False 
TrackResults / Optional Signifies if USPS Tracking by Email | Boolean 
TrackInfo / service is enabled. 
EmailEnabled 


TrackResults / Optional, Populated with the end of day time String 
provided by TRP when TRP API 
indicates the window is “End of 
Day” or when the piece is eligible 
for the PTR default end of day. 
For example: by 5:00pm 
Note: an end of day scenario 
occurs when the TRP API response 
indicates a 0 length window. 
TrackResults / Optional Signifies if the mailpiece is eSOF Boolean Enumerations= 
TrackInfo / eligibile. e True 
eSOFEligible e False 
TrackResults / Optional Expected delivery date. For String 
TrackInfo / example:December 31, 2013 
ExpectedDelivery 
Date 
TrackResults / Optional Expected Delivery Time. For String 
TrackInfo / example: 3:00 PM 
ExpectedDelivery 
Time 
TrackResults / Optional 
TrackInfo / 
ExpectedDelivery Expected Delivery by 
Type 
TrackResults / Optional Guaranteed Delivery Date - Global | String 
TracklInfo / Express Mail only: certain countries 
GuaranteedDeliv provide a guarantee delivery. 
eryDate For example: April 15, 2011 or 3 
Business Days 
TrackResults / Optional Guaranteed Delivery Time provided | String 
TrackInfo / for Priority Mail Express. For 
GuaranteedDeliv example: 3:00 PM 
eryTime 


TrackInfo / used only 

EndOfDay when end 
of day 
condition 
is met 


Populates “Expected Delivery by” if 
there is an EDD. For example: 


String 


TrackResults / Optional Populates “Scheduled Delivery by” String 
TrackInfo / if there is a GDD. For example: 
GuaranteedDeliv Scheduled Delivery by 

eryType 


TrackResults / Optional Special messaging related to the String 
TracklInfo / guarantee. For example: “Loss 
GuaranteedDetail Only Guarantee” 

s 
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TrackResults / Optional Indicates the shape of the item. String Enumerations= 
TracklInfo / e = Letter 
ItemShape e Flat 

e =6Parcel 


e Unknown 


TrackResults / Optional Boolean Enumerations= 
TrackInfo / e §=6True 
Kahalalndicator e False 
TrackResults / Optional String 

TrackInfo / 

MailTypeCode 

TrackResults / Optional Internal date stamp. String 

TrackInfo / 

MPDATE 

TrackResults / Optional Internal suffix. Integer 

TrackInfo / 2010-03-30 19:30:48.224343 

MPSUFFIX 


TrackResults / Optional Field indicating if the item will be String Enumerations= 
TrackInfo / delivered on time as specified in e True 
OnTime the Expected or Guaranteed e False 


delivery date. 


TrackResults / Optional The origin city. String 
TrackInfo / 
OriginCity 


TrackResults / Optional The origin country code. String 

TracklInfo / 

OriginCountryCo 

de 

TrackResults / Optional The origin state. String 

TracklInfo / 

OriginState 

TrackResults / Optional The origin ZIP code. String 

TracklInfo / 

OriginZip 

TrackResults / Optional Signifies if Proof of Delivery service | Boolean Enumerations= 
TracklInfo / is enabled. e True 
PodEnabled e False 
TrackResults / Optional Predicted delivery date. December | String 

TracklInfo / 30, 2013 

PredictedDelivery 

Date 


TrackResults / Optional Predicted Delivery Time 3:00 PM or | String 
TrackInfo / blank. 

PredictedDelivery 

Time 
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a ce Ge 
TrackResults / Optional Populates “Expected Delivery ‘by or | String 

TrackInfo / on’, if the source of the PDD is 
PredictedDelivery TRP API. 
Type Populates “Expected Delivery on” if 

the source of the PDD isa PTR 

calculated date. 

For example: Expected Delivery by 

or Expected Delivery on 
TrackResults / Optional States which system provided the String 
TrackInfoPredicte Predicted Delivery prediction. 
dDeliverySource TRP, AA 
TrackResults / Optional Predicted Delivery Window start String 
TrackInfo / time in am/pm format. 
PDWStart In an EndOfDay scenario, the 

PDWStart tag is null. 

11:00am 

For example: (null) 
TrackResults / Optional Predicted Delivery Window end String 
TrackInfo / time in am/pm format. 
PDWEnd In an EndOfDay scenario, the 

PDWEnd tag is null. 

1:00pm 

For example: (null) 
TrackResults / Optional Contains the Purge By Date of the String 
TrackInfo / mail piece. 
PurgeByDate Example: December 31, 2024 
TrackResults / Optional The related label ID between a String 
TrackInfo / tracking barcode, the core product, 
RelatedRRID and a PS3811, Green Card Return 

Reciept. This field can contain 

either the core product label ID or 

the Green Card label ID. There is 

only a one to one relationship. 

Core Product ID: EA123456795US 

Or Green Card ID; 

95909401 1234567 1234567 


TrackResults / Optional Field indicating if the item qualifies String Enumerations= 
TracklInfo / for redelivery. e True 
Redelivery Enable e False 

d 

TrackResults / Optional Signifies if Restore tracking Boolean Enumerations= 
TrackInfo / information service is enabled e True 
RestoreEnabled Values: e 6False 


TrackResults / Optional Field indicating the date the item String 
TrackInfo / will be Returned to Sender. 

ReturnDateNotic 

e 
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TrackResults / Optional Signifies if Proof of Delivery service | Boolean eel 
TrackInfo / is enabled True 
PodEnabled False 
TrackResults / Optional Signifies if Tracking Proof of Boolean Enumerations= 
TrackInfo / Delivery service is enabled e True 
TpodEnabled False 
TrackResults / Optional Signifies if RRAM service is Boolean aes 
TracklInfo / enabled True 
RRAMenabled False 
TrackResults / Optional Signifies if Return Receipt Boolean ee 
TracklInfo / Electronic service is enabled True 
RreEnabled False 
TrackResults / Optional Additional services purchased String 
TracklInfo / Sadie 
Service 
TrackResults / er Service Type Code of the mail String 
TracklInfo / max 1 piece 
SC eee M, AD, VI, 03, 70, 716 
rrackResults/ Optional For example: Delivered String 
TrackInfo / Status 
TrackResults / Optional For example: In Transit String 
TrackInfo / 
StatusCategory 
TrackResults / Optional Status summary String 
TracklInfo / For example: Your item was 
StatusSummary delivered at 12:55 pm on April 05, 
2010 in FALMOUTH, MA 02540 
TrackResults / Optional Internal description of mail piece as_ | String 
TrackInfo / it relates to PTR (live, history, or 
TABLECODE archived piece) T, H, A (CMC830 
V3 - T is the only value defined) 
TrackResults / Optional Value of Article for when the String 
TracklInfo / Source ID is PIN 
ValueofArticle 
<placeholder> 
TrackResults / Optional Tracking Summary Information. (Group) 
TracklInfo / max 1 
TrackSummary 
TrackResults / Optional The time of the event. String 
TracklInfo / 
TrackSummary / 
EventTime 
TrackResults / Optional The date of the event. String 
TracklInfo / 
TrackSummary / 
EventDate 
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TrackResults / Optional The event type String 
TracklInfo / 
TrackSummary / 
Event 
TrackResults / Optional The city where the event occurred. String 
TracklInfo / 
TrackSummary / 
EventCity 
TrackResults / Optional The state where the event String 
TrackInfo / occurred. 
TrackSummary / 
EventState 
TrackResults / Optional The ZIP Code of the event. String 
TracklInfo / 
TrackSummary / 
EventZIPCode 
TrackResults / Optional The country where the event String 
TrackInfo / occurred. 
TrackSummary / 
EventCountry 
TrackResults / Optional The company name if delivered to String 
TrackInfo / a company. 
TrackSummary / 
FirmName 
TrackResults / Optional The first initial and last name of the | String 
TrackInfo / person signing for delivery (if 
TrackSummary / available). 
Name 
TrackResults / Optional String 
TracklInfo / 
TrackSummary / 
EventCode 
TrackResults / Optional String 
TracklInfo / max 1 
TrackSummary / 
ActionCode 
TrackResults / Optional String 
TracklInfo / 
TrackSummary / 
ReasonCode 


TrackResults / Optional Only eligible to display with delivery | Boolean Enumerations= 
TracklInfo / (01) events. e True 
TrackSummary / e False 


GeoCertified 

TrackResults / Optional Tracking Detail Information. This (Group) 
TracklInfo / max 99 group is repeatable. 

TrackDetail 
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TrackResults / Optional Used to provide additional String Enumerations= 
TrackInfo / information regarding an event e 32 
TrackDetail / posted to a mail piece. 


DeliveryAttribute 
Code 


TrackResults / 
TrackInfo / 
TrackDetail / 
EventTime 


TrackResults / 
TrackInfo / 
TrackDetail / 
EventDate 


TrackResults / 
TrackInfo / 
TrackDetail / 
Event 


TrackResults / 
TrackInfo / 


Optional The time of the event. String 

Optional The date of the event. String 
Optional The event type. String 
Optional The city where the event occurred. String 

TrackDetail / 

EventCity 

TrackResults / Optional The state where the event String 

TrackInfo / occurred. 

TrackDetail / 

EventState 

TrackResults / Optional The status of a posted event on a String 

TrackInfo / mail piece. 

TrackDetail / 

EventStatusCate 

gory 

TrackResults / Optional Stores the name of the shipping String 

TrackInfo / partner associated to a posted 

TrackDetail / shipping partner event (80,81 ,82). 

EventPartner 

TrackResults / Optional The ZIP Code of the event. String 

TrackInfo / 

TrackDetail / 

EventZIPCode 


TrackResults / Optional The country where the event String 
TracklInfo / occurred. 

TrackDetail / 

EventCountry 


TrackResults / 
TrackInfo / 


Optional 


TrackDetail / 
FirmName 


firterrett 


The company name if delivered to String 
a company. 
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TrackResults / Optional The name of the persons signing String 
TrackDetail / for delivery (if available). 
Name 


TrackResults / Optional True/False field indicating the Boolean Enumerations= 
TracklInfo / person signing as an Authorized e True 
TrackDetail / Agent. e False 


AuthorizedAgent 


TrackResults / Optional String 
TrackInfo / 

TrackDetail / 

EventCode 

TrackResults / Optional String 
TrackInfo / max 1 

TrackDetail / 

ActionCode 

TrackResults / Optional String 
TrackInfo / 

TrackDetail / 

ReasonCode 


TrackResults / Optional Only eligible to display with delivery | Boolean Enumerations= 
TracklInfo / (01) events. e True 
TrackDetail / e =6False 
GeoCertified 


TrackResults / Optional (Group) 
TrackInfo / Error 


TrackResults / Optional Assigned number for the type of String 
TracklInfo / Error / error message. 
Number 


TrackResults / Optional Descriptions of error message. String 
TracklInfo / Error / Duplicate or 4 items were also tied 
ErrorDescription to your 3849 ID but exceeded the 

maximum number of tracking 

number inquiries supported on this 

site. 

This 3849 ID was used on a large 

volume shipment and cannot be 

used for tracking on this site. 


TrackResults / Optional (Group) 
TrackInfo / Error 


TrackResponse Required (Alias) 


3.3.2 Sample Response 


Response: Package Tracking “Fields” 
<TrackResponse> 


<TrackInfo ID="XXXXXXXXXXXXXXXXXX"> 
<TrackSummary> 
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<EventTime>10:45 pm</EventTime> 
<EventDate>January 6, 2016</EventDate> 
<Event>Arrived at USPS Facility</Event> 
<EventCity>COLUMBUS</EventCity> 
<EventState>OH</EventState> 
<EventZIPCode>43218</EventZIPCode> 
<EventCountry></EventCountry> 
<FirmName></FirmName> 

<Name></Name> 
<AuthorizedAgent>false</AuthorizedAgent> 
</TrackSummary> 

<TrackDetail> 

<EventTime>9:10 am</EventTime> 
<EventDate>January 6, 2016</EventDate> 
<Event>Acceptance</Event> 

<EventCity>LAKE CHARLES</EventCity> 
<EventState>IL</EventState> 
<EventZIPCode>12345</EventZIPCode> 
<EventCountry></EventCountry> 
<FirmName></FirmName> 

<Name></Name> 
<AuthorizedAgent>false</AuthorizedAgent> 
</TrackDetail> 

</TrackInfo> 

</TrackResponse> 

Response (Revision = 1): Package Tracking “Fields” 
<TrackResponse> 

<TrackInfo ID="XXXXXXXXXXXXXXXXXXXXXKXXKXKXKXKKXKKXKXKKK"> 
<CarrierRelease>false</CarrierRelease> 
<Class>Priority Mail Express&lt;SUP&gt;&amp;reg;&lt;/SUP&gt;</Class> 
<ClassOfMailCode>EX</ClassOfMailCode> 
<DestinationCity>BIRMINGHAM</DestinationCity> 
<DestinationState>AL</DestinationState> 
<DestinationZip>35212</DestinationZip> 
<EmailEnabled>true</EmailEnabled> 
<Kahalalndicator>false</Kahalalndicator> 
<MailTypeCode>DM</MailTypeCode> 
<MPDATE>201 9-08-21 10:44:08.000000</MPDATE> 
<MPSUFFIX>999999999</MPSUFFIX> 
<PodEnabled>true</PodEnabled> 
<TPodEnabled>false</T PodEnabled> 
<RedeliveryEnabled>false</Redelivery Enabled> 
<RestoreEnabled>false</RestoreEnabled> 
<RramEnabled>false</RramEnabled> 
<RreEnabled>false</RreEnabled> 

<Service>PO to Addressee</Service> 

<Service>Up to $100 insurance included</Service> 
<ServiceT ypeCode>701</ServiceTypeCode> 
<Status>Delivered</Status> 
<StatusCategory>Deliverery Attempt, action needed</StatusCategory> 


<StatusSummary>Your item was delivered at 7:30 am on August 21, 2019 in BIRMINGHAM, AL 


35212.</StatusSummary> 
<TABLECODE>T</TABLECODE> 
<TrackSummary> 
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<EventTime>7:30 am</EventTime> 
<EventDate>August 21, 2019</EventDate> 
<Event>CMC1496 SIT testing - Delivered</Event> 
<EventCity>BIRMINGHAM</EventCity> 
<EventState>AL</EventState> 
<EventZIPCode>35212</EventZIPCode> 
<EventCountry></EventCountry> 
<FirmName></FirmName> 

<Name></Name> 
<AuthorizedAgent>false</AuthorizedAgent> 
<EventCode>01</EventCode> 
<EventStatusCategory>CMCXXXxX Delivered</EventStatusCategory> 
</TrackSummary> 

</TrackInfo> 

</TrackResponse> 


Error Response: 
<TrackResponse> 


<TrackInfo ID="XXXXXXXXXXXXXXXXXX"> 

<Error> 

<Numbers>-2147219283</Number> 

<Description>A status update is not yet available on your Priority Mail Express<SUP>&reg;</SUP> 
package. It will be available when the shipper provides an update or the package is delivered to USPS. 
Check back soon. Sign up for Informed Delivery<SUP>&reg;</SUP> to receive notifications for 
packages addressed to you.</Description> 

<HelpFile/> 

<HelpContext/> 

</Error> 

</Tracklnfo> 


4.0 Track and Confirm by Email API 
4.1 Overview 


The Track and Confirm by Email API allows the customer to submit their email address to be notified of 
current or future tracking activity. When you request access for this API, please identify your anticipated 
API volume, mailer ID and how you will be utilizing this API. A mailer identification number (MID) is a 6 or 
9-digit number assigned to a customer through the USPS Business Customer Gateway (BCG). Please 
refer to the following links for help: 

e https://gateway.usps.com/eAdmin/view/knowledge?securityld=MID 

e https://postalpro.usps.com/mailing/mailer-id 


4.1.1 API Signature 
|Scheme | Host Path API XML 


https:// secure.shippingapis.com |} /ShippingAPI.dll? | API=PTSEmail &XML=(see below 
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4.2 Request Descriptions 


= 
PTSEmailRequest |Required API=PTSEmail. (Alias) 


PTSEmailRequest |Required This attribute specifies your Web Tools [String minOccurs="1" 
/ USERID ID. See the Developers Guide for 
information on obtaining your USERID. 
For Example: 
<USERID="XXXXXXXXXXXX’"> 


PTSEmailRequest |Required Must be alphanumeric characters. String minOccurs="1" 
/ Trackld For example: 

<Trackld>EJ123456780US</Trackld> 
PTSEmailRequest |Optional User IP address. String minOccurs="0" 
/ Clientlp For example: 

<Clientlp>127.0.0.0</Clientlp> 
PTSEmailRequest |Optional Internal User Identification. String minOccurs="0" 
/ Sourceld For example: <Sourceld>XYZ 

Corp</Sourceld> 


PTSEmailRequest |Required MPSUFFIX value located in Integer |minOccurs="1" 
/ MpSuffix Track/Confirm Fields API response data. 
Unique to each TrackID. 

For example: 
<MpSuffix>9402</MpSuffix> 


MPDATE value located in Track/Confirm |String 
Fields API response data. Unique to 

each Trackld. 

For example: <MpDate>2009-07-02 
00:42:23.35744</MpDate> 


Enter a notification request type from the |String minOccurs="1" 
maxOccurs ="5” 
Request Descriptions Enumerations= 
Type ° AL 


PTSEmailRequest |Required minOccurs="1" 


“AL” E-Mail Alert e FD 
“FD” E-Mail Future e ED 
Delivery e TD 
“ED” E-Mail e UP 
Delivery/Non e FS 
Delivery activity e OA 
“TD” E-Mail Today 
Delivery 
“UP” E-Mail Available 
for Pickup 
“FS” Package 


addressed to 
me/myusps only 
“OA” Other Activity 

For example: 

<RequestT ype>ED</RequestT ype> 
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PTSEmailRequest |Optional Recipient First Name. String minOccurs="0" 
/ FirstName For example: 

<FirstName>John</FirstName> 
PTSEmailRequest |Optional Recipient Last Name. String minOccurs="0" 
/ LastName For example: 

<LastName>Doe</LastName> 


PTSEmailRequest |Required Complete valid e-mail address is String minOccurs="1" 
/ Email Required if tag is used. 
For example: 

<Email1>cpapple@email.com</Email1> 


PTSEmailRequest |Optional Complete valid e-mail address is String minOccurs="0" 
/ Email2 Required if tag is used. 
PTSEmailRequest |Optional Complete valid e-mail address is String minOccurs="0" 
/ Email3 Required if tag is used. 


PTSEmailRequest [Required once |API=PTSEmail (Alias) 


4.2.1 Sample Request 


Request: PTSEmail 

<PTSEmailRequest USERID="XXXXXXXXXXXX"> 
<Trackld>XXXXXXXXXXX</Trackld > 
<Clientlp>127.2.0.1</Clientlp> 

<Sourceld>XYZ Corp</Sourceld> 

<MpSuffix >9402</MpSuffix> 

<MpDate >2009-07-02 00:42:23.35744</MpDate> 
<RequestType>EN</RequestType> 
<FirstName>John</FirstName> 

<LastName >Doe</LastName> 
<Email1>test@email.com</Email1> 
<Email2></Email2> 

<Email3></Email3> 

</PTSEmailRequest> 


4.3. Response Descriptions 


PTSEmailResponse |Required (Alias) 


PTSEmailResponse |Required Status message. String 
/ ResultText 

PTSEmailRequest / |Required Return code. Integer 
ReturnCode 


PTSEmailResponse |Required (Alias) 
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4.3.1 Sample Response 


Response: PTSEmail 
<PTSEMAILRESULT> 


<ResultText>Your request for all activity to-date will be processed within four hours. Any future activity 
will be processed whenever there is new delivery related event activity.</ResultText> 
<ReturnCode>0</ReturnCode> 

</PTSEMAILRESULT> 


5.0 Proof of Delivery API 
5.1 Overview 


Proof of Delivery is a letter that includes the recipient's name and a copy of their signature. The Proof of 
Delivery API allows the customer to request proof of delivery notification via email. When you request 
access for this API, please identify your anticipated API volume, mailer ID and how you will be utilizing 
this API. A mailer identification number (MID) is a 6 or 9-digit number assigned to a customer through the 
USPS Business Customer Gateway (BCG). Please refer to the following links for help: 


e = https://gateway.usps.com/eAdmin/view/knowledge?securityld=MID 
e = https://postalpro.usps.com/mailing/mailer-id 


5.1.1 API Signature 
|Scheme_ | Host | Path API XML | 


/ShippingAPI.dll? | API=PTSPod | &XML=(see below 


5.2 Request Descriptions 


Sas vae 
PTSPodRequest (Required (Alias) 
once 


PTSPodRequest/ |Required |This attribute specifies your Web Tools ID. See [String |minOccurs="1" 
USERID the Developers Guide for information on 

obtaining your USERID. 

For Example: <USERID="XXXXXXXXXXXX’> 


PTSPodRequest/ |Required |Must be alphanumeric characters. String = |minOccurs="1" 
Trackld For example: 

<Trackld>EJ123456780US</Trackld> 
PTSPodRequest/ |Optional |User IP address. String = |minOccurs="0" 
Clientlp For example: <Clientlp>127.0.0.1</Clientlp> 
PTSPodRequest/ |Optional |Internal User Identification. String = |minOccurs="0" 
Sourceld For example: <Sourceld>XYZ Corp</Sourceld> 


PTSPodRequest/ |Required |MPSUFFIX value located in Track/Confirm integer minOccurs="1" 
Fields API response data. Unique to each 

Trackld. 

For example: <MpSuffix>9402</MpSuffix> 


PTSPodRequest/ |Required |MPDATE value located in Track/Confirm Fields |String |minOccurs="1" 
MpDate API response data. Unique to each TrackID. 
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7 
For example: <MpDate>2009-07-02 
00:42:23.35744</MpDate> 
PTSPodRequest/ |Required |Enter a notification request type from the String = j|minOccurs="1" 
RequestType choices available. 


For example: 
<RequestType>Email</RequestType> 


PTSPodRequest/ |Required |Recipient First Name. String = |minOccurs="1" 
FirstName For example: <FirstName>John</FirstName> 
PTSPodRequest/ |Required |Recipient Last Name. String = |minOccurs="1" 
LastName For example: <LastName>Doe</LastName> 


PTSPodRequest/ |Optional |Required when String = |minOccurs="0" 
Email1 PTSPodRequest[RequestT ype=’Email’]. 
Complete valid e-mail address is Required if tag 
is used. 

For example: 
<Email1>cpapple@email.com</Email1> 


PTSPodRequest/ |Optional |Complete valid e-mail address is Required if tag |String |minOccurs="0" 
Email2 is used. 

PTSPodRequest/ |Optional |Complete valid e-mail address is Required if tag |String |minOccurs="0" 
Email3 is used. 

PTSPodRequest/ |Optional |Fax Number. String = |minOccurs="0" 
FaxNumber 

PTSPodRequest/ |Optional |Address Line 1. String = |minOccurs="0" 
AddressLine1 

PTSPodRequest/ |Optional |Address Line 2. String = |minOccurs="0" 
AddressLine2 

PTSPodRequest/ |Optional |City String = |minOccurs="0" 
City 

PTSPodRequest/ |Optional |State String = |minOccurs="0" 
State 

PTSPodRequest/ |Optional Zip String = |minOccurs="0" 
Zip 

PTSPodRequest/ |Optional |Indicates whether or not address should be Boolean minOccurs="0" 
VerifyAddress validated. 


PTSPodRequest/ |Required |TableCode value located in Track/Confirm String = j|minOccurs="1" 
Fields API response data. Unique to each 
TrackID. 

For example: <TableCode>T</TableCode> 


PTSPodRequest/ |Optional |Unique 10-byte numeric value that’s associated |String |minOccurs="0" 
CustRegID to each user. 
PTSPodRequest |Required (Alias) 

once 
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5.2.1 Sample Request 


Request: PTSPod 
<PTSPodRequest USERID="XXXXXXXXXXXX"> 


<Trackld>XXXXXXXXXXX</Trackld > 
<Clientlp>127.0.0.1</Clientlp> 
<Sourceld>XXXXXX</Sourceld> 
<MpSuffix>9402</MpSuffix> 
<MpDate>2009-07-02 00:42:23.35744</MpDate> 
<RequestType>Email</RequestT ype> 
<FirstName>John</FirstName> 
<LastName>Doe</LastName> 
<Email1>test@email.com </Email1> 
<Email2></Email2> 

<Email3></Email3> 
<TableCode>T</TableCode> 
<CustRegID>1234567890</CustRegID> 
</PTSPodRequest> 


5.3 Response Descriptions 


PTSPODResult Required (Alias) 


PTSPODResponse |Required |Status message. String 
/ ResultText 
PTSPODRedquest/ |Required |Return code. Integer 
ReturnCode 


PTSPODResult Required (Alias) 


5.3.1 Sample Response 


Response: PTSPOD 
<PTSPODRESULT> 


<ResultText>Your Proof of Delivery record is complete and will be processed shortly.</ResultText> 
<ReturnCode>0</ReturnCode> 
</PTSPODRESULT> 


6.0 Return Receipt Electronic API 
6.1 Overview 


The Return Receipt Electronic API allows the customer to request a copy of the proof of delivery record 
via email. When you request access for this API, please identify your anticipated API volume, mailer ID 
and how you will be utilizing this API. A mailer identification number (MID) is a 6 or 9-digit number 
assigned to a customer through the USPS Business Customer Gateway (BCG). Please refer to the 
following links for help: 


e = https://gateway.usps.com/eAdmin/view/knowledge?securitylId=MID 
e https://postalpro.usps.com/mailing/mailer-id 
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6.1.1 API Signature 
|Scheme Host Path API XML | 


httos:// | secure.shippingapis.com __| /ShippingAPI.dll?_ | API=PTSRre_ | &XML=(see below) 
6.2 Request Descriptions 


PTSRreRequest |/Required |API=PTSRre (Alias) 


PTSRreRequest |Required This attribute specifies your Web Tools ID. |String 

See the Developers Guide for information 

on obtaining your USERID. 

For Example: 

<USERID="XXXXXXXXXXXX’> 
PTSRreRequest |Required Must be alphanumeric characters. String minOccurs="1" 
/ Trackld For example: 

<Trackld>EJ123456780US</Trackld> 
PTSRreRequest Optional User IP address. String minOccurs="0" 
/ Clientlp For example: 

<Clientlp>127.0.0.1</Clientlp> 
PTSRreRequest |Optional |Internal User Identification. String minOccurs="0" 
/ Sourceld For example: <Sourceld>XYZ 

Corp</Sourceld> 


PTSRreRequest |Required |MPSUFFIX value located in integer minOccurs="1" 
/ MpSuffix Track/Confirm Fields API response data. 
Unique to each Trackld. 

For example: <MpSuffix>9402</MpSuffix> 


PTSRreRequest |Required IMPDATE value located in Track/Confirm —|String 
Fields API response data. Unique to each 
TrackID. 

For example: <MpDate>2009-07-02 
00:42:23.35744</MpDate> 


PTSRreRequest /Required /Recipient First Name. String minOccurs="1" 
/ FirstName For example: 

<FirstName>John</FirstName> 
PTSRreRequest |Required Recipient Last Name. String minOccurs="1" 
/ LastName For example: 

<LastName>Doe</LastName> 


PTSRreRequest |Required Complete valid e-mail address is Required |String minOccurs="1" 
/ Email if tag is used. 


minOccurs="1" 


<Email1>cgpapple@email.com</Email1> 


PTSRreRequest |Optional |Complete valid e-mail address is Required |String minOccurs="0" 
/ Email2 if tag is used. 
PTSRreRequest |Optional |Complete valid e-mail address is Required |String minOccurs="0" 
/ Email3 if tag is used. 
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_le | i 


PTSRreRequest |Required |TableCode value located in Track/Confirm |String minOccurs="1" 
Fields API response data. Unique to each 
TrackID. 

For example: 
<TableCode>T</TableCode> 


PTSRreRequest |Optional Unique 10-byte numeric value that is String minOccurs="0" 
/ CustRegID associated to each user. 


PTSRreRequest |Required (Alias) 


6.2.1 Sample Request 


Request: PTSRre 
<PTSRreRequest USERID="XXXXXXXXXXXX"> 


<Trackld>XXXXXXXXXXX</Trackld > 
<Clientlp>127.0.0.1</Clientlp> 
<Sourceld>XYZ Corp</Sourceld> 
<MpSuffix>9402</MpSuffix> 
<MpDate>2009-07-02 00:42:23.35744</MpDate> 
<FirstName>John</FirstName> 
<LastName>Doe</LastName> 
<Email1>cpapple@email.com</Email1> 
<Email2></Email2> 

<Email3></Email3> 
<TableCode>T</TableCode> 
<CustRegID>1234567890</CustRegID> 
</PTSRreRequest> 


6.3 Response Descriptions 


PTSRreResult Required ee (Alias) fo 
PTSRreResponse 

/ ResultText Required |Status message. String 
PTSRreRequest / 

ReturnCode Required Retumcod. Integer 


PTSRreResult Required (Alias) 


6.3.1 Sample Response 


Response: PTSRre 
<PTSRRERESULT> 


<ResultText>Your Proof of Delivery record is complete and will be processed 
shortly</ResultText> 

<ReturnCode>0</ReturnCode> 

</PTSRRERESULT> 
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7.0 Track Proof of Delivery API 
7.1. Overview 


Track Proof of Delivery is a letter that includes the recipient's name and a copy of their signature. The 
Track Proof of Delivery API allows the customer to request proof of delivery notification via email. When 
you request access for this API, please identify your anticipated API volume, mailer ID and how you will 
be utilizing this API. A mailer identification number (MID) is a 6 or 9-digit number assigned to a customer 
through the USPS Business Customer Gateway (BCG). Please refer to the following links for help: 


e = https://gateway.usps.com/eAdmin/view/knowledge?securityld=MID 
e = https://postalpro.usps.com/mailing/mailer-id 


7.1.1 API Signature 
|Scheme Host Path API | XML | 


| https:// | secure.shippingapis.com | /ShippingAPI.dil? | API=PTSTPod | &XML=(see below 
7.2 Request Descriptions 


a me I | ail 
Tag Name Descriptions ilies Validation 
PTSTPodRequest |Required (Alias) 


PTSTPodRequest |Required |This attribute specifies your Web Tools ID. (String |minOccurs="1" 
See the Developers Guide for information 
on obtaining your USERID. 

For Example: 
<USERID="XXXXXXXXXXXX’> 


Fields API response data. Unique to each 
Trackld. 
For example: <MpSuffix>9402</MpSuffix> 


PTSTPodRequest |Required |MPDATE value located in Track/Confirm String |minOccurs="1" 
/ MpDate Fields API response data. Unique to each 

TrackID. 

For example: <MpDate>2009-07-02 

00:42:23.35744</MpDate> 


PTSTPodRequest |Required |Enter a notification request type from the String |minOccurs="1" 
/ RequestType choices available. 

For example: 

<RequestType>Email</RequestType> 


PTSTPodRequest |Required |Recipient First Name. String |minOccurs="1" 
/ FirstName For example: 

<FirstName>John</FirstName> 
PTSTPodRequest |Required |Recipient Last Name. String |minOccurs="1" 
/ LastName For example: 

<LastName>Doe</LastName> 
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iano ee 
| 


PTSTPodRequest |Optional |Required when String |minOccurs="0" 
/ Email PTSTPodRequest[RequestT ype=’Email’]. 
Complete valid e-mail address is Required if 
tag is used. 

For example: 
<Email1>cpapplee@email.com</Email1> 


PTSTPodRequest |Optional |Complete valid e-mail address is Required if |String |minOccurs="0" 
/ Email2 tag is used. 

PTSTPodRequest |Optional |Complete valid e-mail address is Required if |String |minOccurs="0" 
/Email3 tag is used. 

PTSTPodRequest |Required |Unique 10-byte numeric value that’s String |minOccurs="0" 
/ CustRegID associated to each user. 


PTSTPodRequest |Required |TableCode value located in Track/Confirm |String |minOccurs="1" 
/ TableCode Fields API response data. Unique to each 
TrackID. 

For example: <TableCode>T</TableCode> 


PTSTPodRequest |Optional User IP address. String |minOccurs="0" 
/ Clientlp For example: 
<Clientlp>133.2.1.1</Clientlp> 


PTSTPodRequest |Optional |Internal User Identification. Required when [String |minOccurs="0" 
/ Sourceld TrackFieldRequest[Revision='1’]. 

For example: <SourcelD>XYZ 

Corp</SourcelD> 


PTSTPodRequest |Required (alias) 


7.2.1 Sample Request 


Request: PTSTPod 
<PTSTPodRequest USERID="XXXXXXXXXXXX"> 


<Trackld>XXXXXXXXXXX</Trackld > 
<MpSuffix>9402</MpSuffix> 
<MpDate>2009-07-02 00:42:23.35744</MpDate> 
<RequestType>Email</RequestType> 
<FirstName>John</FirstName> 
<LastName>Doe</LastName> 
<Email1>cpapple@email.com </Email1> 
<Email2></Email2> 

<Email3></Email3> 
<CustRegID>1234567890</CustRegID> 
<TableCode>T</TableCode> 
<Clientlp>127.0.0.1</Clientlp> 
<Sourceld>IVR</Sourceld> 
</PTSTPodRequest> 


29 


USPS Web Tools User Guide 
7.3. Response Descriptions 


PTSTPODResult Required (Alias) 


PTSTPODResponse ; 

/ ResultText Required |Status message. String Ys 
PTSTPODRequest / F 

ReturnCode Required Retumcod, Integer po 


PTSTPODResult Required (Alias) 
7.3.1 Sample Response 


Response: PTSTPod 
<PTSTPODRESULT> 


<ResultText>Your Proof of Delivery record is complete and will be processed shortly.</ResultText> 
<ReturnCode>0</ReturnCode> 


</PTSTPODRESULT> 
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